// 定义包路径，属于驾校相关的Web控制器
package com.ruoyi.web.controller.jiaxiao;

// 导入Java工具类
import java.util.List;
import javax.servlet.http.HttpServletResponse;  // 用于处理HTTP响应
// 导入Spring框架相关注解和类
import org.springframework.security.access.prepost.PreAuthorize;  // 方法级权限控制注解
import org.springframework.beans.factory.annotation.Autowired;  // 依赖注入注解
import org.springframework.web.bind.annotation.GetMapping;  // 处理GET请求的注解
import org.springframework.web.bind.annotation.PostMapping;  // 处理POST请求的注解
import org.springframework.web.bind.annotation.PutMapping;  // 处理PUT请求的注解
import org.springframework.web.bind.annotation.DeleteMapping;  // 处理DELETE请求的注解
import org.springframework.web.bind.annotation.PathVariable;  // 获取URL路径参数的注解
import org.springframework.web.bind.annotation.RequestBody;  // 接收请求体数据的注解
import org.springframework.web.bind.annotation.RequestMapping;  // 定义请求路径的注解
import org.springframework.web.bind.annotation.RequestParam;  // 获取请求参数的注解
import org.springframework.web.bind.annotation.RestController;  // 标识REST风格控制器的注解
// 导入若依框架相关注解和类
import com.ruoyi.common.annotation.Log;  // 日志记录注解
import com.ruoyi.common.core.controller.BaseController;  // 基础控制器类
import com.ruoyi.common.core.domain.AjaxResult;  // 接口返回结果封装类
import com.ruoyi.common.enums.BusinessType;  // 业务操作类型枚举
// 导入补考安排相关的实体类和服务接口
import com.ruoyi.system.domain.JxRetakeSchedule;  // 补考安排实体类
import com.ruoyi.system.service.IJxRetakeScheduleService;  // 补考安排服务接口
import com.ruoyi.common.utils.poi.ExcelUtil;  // Excel处理工具类
import com.ruoyi.common.core.page.TableDataInfo;  // 分页数据封装类

/**
 * 补考安排Controller
 * 处理与补考安排相关的HTTP请求
 *
 * @author ruoyi
 * @date 2025-01-27
 */
@RestController  // 标识为REST风格控制器，返回结果自动转为JSON
@RequestMapping("/jiaxiao/retake")  // 定义请求路径前缀，所有接口路径以此开头
public class JxRetakeScheduleController extends BaseController  // 继承基础控制器，获取分页等通用功能
{
    // 自动注入补考安排服务接口，用于调用业务逻辑层方法
    @Autowired
    private IJxRetakeScheduleService jxRetakeScheduleService;

    /**
     * 查询补考安排列表
     * @param jxRetakeSchedule 包含查询条件的补考安排实体对象
     * @return 分页后的补考安排列表数据
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:list')")  // 权限控制，需有指定权限才能访问
    @GetMapping("/list")  // 处理GET请求，完整路径为/jiaxiao/retake/list
    public TableDataInfo list(JxRetakeSchedule jxRetakeSchedule)
    {
        startPage();  // 开启分页，从请求参数中获取分页信息
        // 调用服务层查询补考安排列表
        List<JxRetakeSchedule> list = jxRetakeScheduleService.selectJxRetakeScheduleList(jxRetakeSchedule);
        return getDataTable(list);  // 封装分页结果并返回
    }

    /**
     * 导出补考安排列表
     * @param response HTTP响应对象，用于输出Excel文件
     * @param jxRetakeSchedule 包含查询条件的补考安排实体对象
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:export')")  // 权限控制
    @Log(title = "补考安排", businessType = BusinessType.EXPORT)  // 记录导出日志
    @PostMapping("/export")  // 处理POST请求，路径为/jiaxiao/retake/export
    public void export(HttpServletResponse response, JxRetakeSchedule jxRetakeSchedule)
    {
        // 查询要导出的补考安排数据
        List<JxRetakeSchedule> list = jxRetakeScheduleService.selectJxRetakeScheduleList(jxRetakeSchedule);
        // 创建Excel工具类实例
        ExcelUtil<JxRetakeSchedule> util = new ExcelUtil<JxRetakeSchedule>(JxRetakeSchedule.class);
        // 导出Excel文件到响应流
        util.exportExcel(response, list, "补考安排数据");
    }

    /**
     * 获取补考安排详细信息
     * @param retakeId 补考安排ID
     * @return 包含补考安排详情的AjaxResult对象
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:query')")  // 权限控制
    @GetMapping(value = "/{retakeId}")  // 处理GET请求，路径为/jiaxiao/retake/{retakeId}
    public AjaxResult getInfo(@PathVariable("retakeId") Long retakeId)
    {
        // 调用服务层查询详情并返回成功结果
        return success(jxRetakeScheduleService.selectJxRetakeScheduleByRetakeId(retakeId));
    }

    /**
     * 新增补考安排
     * @param jxRetakeSchedule 包含新增补考安排信息的实体对象
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:add')")  // 权限控制
    @Log(title = "补考安排", businessType = BusinessType.INSERT)  // 记录新增日志
    @PostMapping  // 处理POST请求，路径为/jiaxiao/retake
    public AjaxResult add(@RequestBody JxRetakeSchedule jxRetakeSchedule)
    {
        // 调用服务层新增方法，返回操作结果
        return toAjax(jxRetakeScheduleService.insertJxRetakeSchedule(jxRetakeSchedule));
    }

    /**
     * 修改补考安排
     * @param jxRetakeSchedule 包含修改后补考安排信息的实体对象
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:edit')")  // 权限控制
    @Log(title = "补考安排", businessType = BusinessType.UPDATE)  // 记录更新日志
    @PutMapping  // 处理PUT请求，路径为/jiaxiao/retake
    public AjaxResult edit(@RequestBody JxRetakeSchedule jxRetakeSchedule)
    {
        // 调用服务层更新方法，返回操作结果
        return toAjax(jxRetakeScheduleService.updateJxRetakeSchedule(jxRetakeSchedule));
    }

    /**
     * 删除补考安排
     * @param retakeIds 要删除的补考安排ID数组
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:remove')")  // 权限控制
    @Log(title = "补考安排", businessType = BusinessType.DELETE)  // 记录删除日志
    @DeleteMapping("/{retakeIds}")  // 处理DELETE请求，路径为/jiaxiao/retake/{retakeIds}
    public AjaxResult remove(@PathVariable Long[] retakeIds)
    {
        // 调用服务层批量删除方法，返回操作结果
        return toAjax(jxRetakeScheduleService.deleteJxRetakeScheduleByRetakeIds(retakeIds));
    }

    /**
     * 查询学员的待考试补考安排
     * @param studentId 学员ID
     * @param subjectId 科目ID
     * @return 包含待考补考安排的AjaxResult对象
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:query')")  // 权限控制
    @GetMapping("/student/{studentId}/subject/{subjectId}")  // 处理GET请求，路径包含学员ID和科目ID
    public AjaxResult getPendingRetakeByStudentAndSubject(@PathVariable("studentId") Long studentId,
                                                          @PathVariable("subjectId") Long subjectId)
    {
        // 调用服务层查询指定学员指定科目的待考补考安排
        JxRetakeSchedule retakeSchedule = jxRetakeScheduleService.selectPendingRetakeByStudentAndSubject(studentId, subjectId);
        return success(retakeSchedule);  // 返回查询结果
    }

    /**
     * 查询学员所有待考试的补考安排
     * @param studentId 学员ID
     * @return 包含所有待考补考安排列表的AjaxResult对象
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:query')")  // 权限控制
    @GetMapping("/student/{studentId}")  // 处理GET请求，路径包含学员ID
    public AjaxResult getPendingRetakesByStudent(@PathVariable("studentId") Long studentId)
    {
        // 调用服务层查询指定学员的所有待考补考安排
        List<JxRetakeSchedule> list = jxRetakeScheduleService.selectPendingRetakesByStudent(studentId);
        return success(list);  // 返回查询结果
    }

    /**
     * 查询指定日期范围内的补考安排
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 包含日期范围内补考安排列表的AjaxResult对象
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:query')")  // 权限控制
    @GetMapping("/calendar")  // 处理GET请求，路径为/jiaxiao/retake/calendar
    public AjaxResult getRetakeScheduleByDateRange(@RequestParam("startDate") String startDate,
                                                   @RequestParam("endDate") String endDate)
    {
        // 调用服务层查询指定日期范围内的补考安排
        List<JxRetakeSchedule> list = jxRetakeScheduleService.selectRetakeScheduleByDateRange(startDate, endDate);
        return success(list);  // 返回查询结果
    }

    /**
     * 完成补考安排
     * @param retakeId 补考安排ID
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:edit')")  // 权限控制
    @Log(title = "完成补考安排", businessType = BusinessType.UPDATE)  // 记录完成操作日志
    @PutMapping("/complete/{retakeId}")  // 处理PUT请求，路径包含补考安排ID
    public AjaxResult complete(@PathVariable("retakeId") Long retakeId)
    {
        // 调用服务层完成补考安排的方法，返回操作结果
        return toAjax(jxRetakeScheduleService.completeRetakeSchedule(retakeId));
    }

    /**
     * 取消补考安排
     * @param retakeId 补考安排ID
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:retake:edit')")  // 权限控制
    @Log(title = "取消补考安排", businessType = BusinessType.UPDATE)  // 记录取消操作日志
    @PutMapping("/cancel/{retakeId}")  // 处理PUT请求，路径包含补考安排ID
    public AjaxResult cancel(@PathVariable("retakeId") Long retakeId)
    {
        // 调用服务层取消补考安排的方法，返回操作结果
        return toAjax(jxRetakeScheduleService.cancelRetakeSchedule(retakeId));
    }
}